<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.  -*-Text-*- -->
<!-- Function Description: Array Functions -->

<div class='chapter'>4. Arrays</div><p class='cindent'><!-- array -->
<!-- Fill pointers have to be explained. -->
<!-- Some stuff here not really documented, because it should be flushed. -->

<div class='section'>4.1 What Arrays Are</div>	An <font class="italic">array</font> is a Lisp object that consists of a group of cells,
each of which may contain a Lisp object.  The individual cells are
selected by numerical <font class="italic">subscripts</font>.
<p class='cindent'><!-- "subscript" -->

<p class='cindent' id='array-type'><!-- types of arrays -->
	There are many types of arrays.  Some types of arrays can hold
Lisp objects of any type; the other types of arrays can only hold
fixnums.  The array types are known by a set of symbols symbols whose names
begin with "<font class="lisp">art-</font>" (for ARray Type).

.defvar array-types
The value of <font class="lisp">array-types</font> is a list of all of the array type symbols
such as <font class="lisp">art-q</font>, <font class="lisp">art-4b</font>, <font class="lisp">art-string</font> and so on.
.end_defvar

<div class='defun'><font class='exdent'><font class='funcname'>array-types <font class='italic' color='purple'>array-type-code</font></font></font><br>
An array of the array type symbols, indexed
by their internal numeric codes.
</div>

.defvar array-elements-per-q
<font class="lisp">array-elements-per-q</font> is an association list (see <a href='fd_con.html#alist'>this link</a>) which
associates each array type symbol with the number of array elements
stored in one word, for an array of that type.  If the value is negative,
it is instead the number of words per array element, for arrays whose
elements are more than one word long.
.end_defvar

<div class='defun'><font class='exdent'><font class='funcname'>array-elements-per-q <font class='italic' color='purple'>array-type-code</font></font></font><br>
This is an array, indexed by the internal codes of the array types,
containing the number of array elements stored in one word, for an
array of that type.  If the value is negative,
it is instead the number of words per array element, for arrays whose
elements are more than one word long.
</div>

.defvar array-bits-per-element
The value of <font class="lisp">array-bits-per-element</font> is an association list (see <a href='fd_con.html#alist'>this link</a>)
which associates each array type symbol with the number of
bits of unsigned number it can hold, or <font class="lisp">nil</font> if it can
hold Lisp objects.  This can be used to tell whether an array
can hold Lisp objects or not.
.end_defvar

<div class='defun'><font class='exdent'><font class='funcname'>array-bits-per-element <font class='italic' color='purple'>array-type-code</font></font></font><br>
This is an array, indexed by the internal codes of the array types, containing
the number of bits per cell for unsigned numeric arrays, and <font class="lisp">nil</font> for
full-Lisp-object-containing array.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-element-size <font class='italic' color='purple'>array</font></font></font><br>
Given an array, returns the number of bits that fit in an element of that
array.  For non-numeric arrays, the result is 24., assuming you will be
storing unsigned fixnums in the array.
</div>

	The most commonly used type is called <font class="lisp">art-q</font>.  An <font class="lisp">art-q</font> array simply
holds Lisp objects of any type.

	Similar to the <font class="lisp">art-q</font> type is the <font class="lisp">art-q-list</font>.  Like the <font class="lisp">art-q</font>,
its elements
may be any Lisp object.  The difference is that the <font class="lisp">art-q-list</font> array "doubles"
as a list; the function <font class="lisp">g-l-p</font> will take an <font class="lisp">art-q-list</font> array and return
a list object whose elements are those of the array, and whose actual substance
is that of the array.  If you <font class="lisp">rplaca</font> elements of the list, the corresponding
element of the array will change, and if you store into the array, the corresponding
element of the list will change the same way.

	There is a set of types called <font class="lisp">art-1b, art-2b, art-4b, art-8b</font> 
and <font class="lisp">art-16b</font>;
these names are short for "1 bit", "2 bits", and so on.  Each element
of an <font class="lisp">art-1b</font> array is a fixnum, and only one bit (the least significant)
is remembered in the array; all of the others are discarded.  Similarly,
in an <font class="lisp">art-2b</font> array, only the two least significant bits are remembered.
So if you store a 5 into an <font class="lisp">art-2b</font> array, for example, and look at it
later, you will find a 1 rather than a 5.
	These arrays are used when it is known beforehand that the
fixnums which will be stored are non-negative and limited in size to a
certain number of bits.  Their advantage over the <font class="lisp">art-q</font> array is
that they occupy less storage, because more than one element of the
array is kept in a single machine word.  (For example, 32 elements
(decimal) of an <font class="lisp">art-1b</font> array or 2 elements of an <font class="lisp">art-16b</font> array
will fit into one word).

	Character strings are implemented by the <font class="lisp">art-string</font> array
type.  This type acts similarly to the <font class="lisp">art-8b</font>; its elements must be
fixnums, of which only the least significant eight bits are stored. 
However, many important system functions, including <font class="lisp">read</font>,
<font class="lisp">print</font>, and <font class="lisp">eval</font>, treat <font class="lisp">art-string</font> arrays very differently from
the other kinds of arrays.  These arrays are usually called 
<font class="italic">string</font>s, and an entire chapter of this manual deals with
functions which manipulate them. 

	There are three types of arrays which exist only for the
purposes of <font class="italic">stack groups</font>; these types are called
<font class="lisp">art-stack-group-head, art-special-pdl</font> and <font class="lisp">art-reg-pdl</font>.  Their elements
may be any Lisp object; their use is explained in the section on
stack groups (see <a href='fd_sg.html#stack-group'>this link</a>).
<p class='cindent'><!-- "stack group" -->

	The <font class="lisp">art-float</font> array type is a special purpose type whose elements
are flonums.  When storing into such an array the value will be converted to
a flonum.  The advantage of storing flonums in an <font class="lisp">art-float</font> array rather
than an <font class="lisp">art-q</font> array is that the numbers in an <font class="lisp">art-float</font> array are
not true Lisp objects.  Instead the array remembers the numerical value, and
when it is <font class="lisp">aref</font>'ed creates a Lisp object (a flonum) to hold the value.
Because the system does special storage management for bignums and flonums
that are intermediate results the use of <font class="lisp">art-float</font> arrays can save a lot
of work for the garbage-collector and hence greatly increase performance.
An intermediate result is a Lisp object passed as an argument, stored in a local variable,
or returned as the value of a function, but not stored into a global variable,
an array, or list structure.  <font class="lisp">art-float</font> arrays also provide a locality
of reference advantage over <font class="lisp">art-q</font> arrays containing flonums.

<div class='section'>4.2 How Arrays Work</div>
	The <font class="italic">dimensionality</font> of an array (or, the number of dimensions
which the array has) is the number of subscripts used to
refer to one of the elements of the array.  The dimensionality
may be any integer from one to seven, inclusively.
<!-- How about zero? -->

	The lowest value for any subscript is zero; the highest value
is a property of the array.  Each dimension has a size, which is
the lowest number which is too great to be used as a subscript.
For example, in a one dimensional array of five elements, the size
of the one and only dimension is five, and the acceptable
values of the subscript are zero, one, two, three, and four.

	The most basic primitive functions for handling arrays are:
<font class="lisp">make-array</font>, which is used for the creation of arrays, <font class="lisp">aref</font>,
which is used for examining the
contents of arrays, and <font class="lisp">aset</font>, which
is used for storing into arrays.

	An array is a regular Lisp object, and it is common for an
array to be the binding of a symbol, or the car or cdr of a cons,
or, in fact, an element of an array.  Another way of handling
arrays, inherited from Maclisp, is to treat them as functions.
In this case each array has a name, which is a symbol whose function
definition is the array.  The Lisp machine supports this style by
allowing an array to be <font class="italic">applied</font> to arguments, as if it were a function.  The
arguments are treated as subscripts and the array is referenced
appropriately.  The <font class="lisp">store</font> special form (see (store-fun)) is also
supported.  This form of array referencing is considered to be obsolete,
and should not be used in new programs.

	Here are some issues of Maclisp compatibility:

	Fixnum arrays do not exist (however, see the Lisp machine's small-positive-number
arrays).  Flonum arrays exist but you do not use them in the same way; no
declarations are required or allowed.
"Un-garbage-collected" arrays do not exist.
'c yet??? --weak links
Readtables and obarrays are represented as arrays, but unlike Maclisp special
array types are not used.  See the descriptions
of <font class="lisp">read</font> ((read-fun)) and <font class="lisp">intern</font> ((intern-fun)) for
information about readtables and obarrays (packages).
There are no "dead" arrays, nor are Multics "external" arrays provided.

The <font class="lisp">arraycall</font> function is not used (see <font class="lisp">aref</font>, (aref-fun).)

Subscripts are always checked for validity, regardless of the value
of <font class="lisp">*rset</font> and whether the code is compiled or not. 
However, in a multi-dimensional array, an error is only caused
if the subscripts would have resulted in a reference to storage
outside of the array; so if you have a 2 by 7 array and refer
to an element with subscripts 3 and 1, no error will
be caused despite the fact that the reference is invalid;
but if you refer to element 1 by 100, an error will be caused.
In other words, any subscript error which is not detected
will only refer to somewhere else in your array, and not
to any other part of storage.

Currently multi-dimensional arrays are stored in column-major order
rather than row-major order as in Maclisp.  This has an effect on
paging performance when using large arrays.  Row-major order means
that successive memory locations differ in the last subscript,
while column-major order means that successive memory locations differ
in the first subscript.

<font class="lisp">loadarrays</font> and <font class="lisp">dumparrays</font> are not provided.  However,
arrays can be put into "QFASL" files; see the section on fasloading
((fasload-fun)).

<div class='section'>4.3 Extra Features of Arrays</div><p class='cindent'><!-- "array leader" -->
	Any array may have an <font class="italic">array leader</font>.  An array leader is
like a one-dimensional <font class="lisp">art-q</font> array which is attached to the main array.  So
an array which has a leader acts like two arrays joined together.  It
can be stored in and examined by a special set of functions which are
analogous to those used for the main array: <font class="lisp">array-leader</font> and
<font class="lisp">store-array-leader</font>.  The leader is always one-dimensional, and
always can hold any kind of Lisp object, regardless of the type or
dimensionality of the array.

	By convention, the zeroth element of the array leader of
an array is used to hold the number of elements in the array
that are "active" in some sense.  When the zeroth element is used
this way, it is called a <font class="italic">fill pointer</font>.
<p class='cindent'><!-- "fill pointer" -->
Specifically, if a string (an array of type <font class="lisp">art-string</font>) has
seven elements, but it has a fill pointer of five, then only elements
zero through four of the string are considered to be "active";  the string's
printed representation will be five characters long, string-searching
functions will stop after the fifth element, etc.

	The second element is also used in conjunction with the "named
structure" feature; see <a href='dfstr.html#named-structure'>this link</a>.

<p class='cindent'><!-- "displaced array" -->
	The following explanation of <font class="italic">displaced arrays</font>
is probably not of interest to a beginner; the section may
be passed over without losing the continuity of the manual.

	Normally, an array consists of a small amount of header information,
followed by the contents of the array.  However, sometimes it is desirable
to have the header information removed from the actual contents.  One
such occasion is when the contents of the array must be located in a
special part of the Lisp Machine's address space, such as the area used
for the control of input/output devices.  Displaced arrays are also
used to reference certain special system tables, which are at fixed
addresses so the microcode can access them easily.

	If you give <font class="lisp">make-array</font> a fixnum as its fourth argument,
it will create a displaced array refering to that location of virtual memory.
References to elements of the displaced array will access that part
of storage, and return the contents; the regular <font class="lisp">aref</font> and
<font class="lisp">aset</font> functions are used.  If the array is one whose elements
are Lisp objects, caution should be used: if the region of address
space does not contain typed Lisp objects, the integrity of the storage
system could be damaged by the garbage collector.  If the array is one
whose elements are bytes (such as an <font class="lisp">art-4b</font> type), then there
is no problem.  It is important to know, in this case, that the elements
of such arrays are allocated from the right to the left within the 32-bit
words.  See the description of internal array formats on (array-format).

<p class='cindent'><!-- "indirect array" -->
<p class='cindent' id='indirect-array'><!-- indirect arrays -->
	It is also possible to have an array whose contents, instead
of being located at a fixed place in virtual memory, are defined
to be those of another array.  Such an array is called an <font class="italic">indirect array</font>,
and is created by giving <font class="lisp">make-array</font> an array as its fourth argument.
The effects of this are simple if both arrays have the same type; the two
arrays share all elements.  An object stored in a certain element
of one can be retrieved from the corresponding element of the other.
This, by itself, is not very useful.  However, if the arrays have
different dimensionality, the manner of accessing the elements differs.
Thus, by creating a one-dimensional array of nine elements which was
indirected to a second, two-dimensional array of three elements by three,
then the elements could be accessed in either a one-dimensional or
a two-dimensional manner.  Even more complex effects can be produced if
the new array is of a different type than the old array; see the description
of internal array formats on (array-format).

<p class='cindent'><!-- "index offset" -->
	It is also possible to create a one-dimensional indirect array
in such a way that when an attempt is made to reference it or store
into it, a constant number is added to the subscript given.  This
number is called the <font class="italic">index-offset</font>, and is specified at the time
the indirect array is created, by giving a fixnum to <font class="lisp">make-array</font> as
its sixth argument.  The <font class="lisp">nsubstring</font> function (see (nsubstring-fun)) creates such
arrays. 
'findex "nsubstring"

<div class='section'>4.4 Basic Array Functions</div>
<div class='defun'><font class='exdent'><font class='funcname'>make-array <font class='italic' color='purple'>area type dims &optional displaced-p leader index-offset named-structure</font></font></font><br>
	This creates and returns an array, according to various specifications.   

	The <font class="italic">area</font> parameter specifies the area in which to allocate
the array's storage; if you are not concerned with areas, simply use <font class="lisp">nil</font>
which as always means the default area.

	<font class="italic">type</font> should be a symbolic name of an array type; the most
common of these is <font class="lisp">art-q</font>.  The elements of the array are
initialized according to the type:  if the array is of a type whose
elements may only be fixnums or flonums, then every element of the array will
initially be <font class="lisp">0</font>; otherwise, every element will initially be
<font class="lisp">nil</font>.  See the description of array types on <a href='fd_arr.html#array-type'>this link</a>.
<p class='cindent' id='index-offset'><!-- "array initialization" -->

	<font class="italic">dims</font> should be a list of fixnums which are the dimensions of the array;
the length of the list will be the dimensionality of the array.  For convenience,
if the dimensionality should be one, the single dimension may be provided as
a fixnum rather than a list of one fixnum.

<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(setq a (make-array nil 'art-q 5))       <font class="main">; Create a one-d array</font>
					 <font class="main">;of 5 elements.</font>

(setq b (make-array nil 'art-4b '(3 4))) <font class="main">; Create a four-bit two-d</font>
					 <font class="main">;array, 3 by 4.</font>
</pre>

	If <font class="italic">displaced-p</font> is not <font class="lisp">nil</font>, then the array will be a <font class="italic">displaced</font>
array.  <font class="italic">displaced-p</font> may either be a fixnum, to create a regular displaced array
which refers to a certain section of virtual address space, or an array, to create
an indirect array (see <a href='fd_arr.html#indirect-array'>this link</a>).
<p class='cindent'><!-- "displaced array" -->
<p class='cindent'><!-- "indirect array" -->

	If <font class="italic">leader</font> is not <font class="lisp">nil</font>, then the array will be given a
leader.  If <font class="italic">leader</font> is a fixnum, the array's leader will be
<font class="italic">leader</font> elements long, and its elements will be initialized to
<font class="lisp">nil</font>.  <font class="italic">Leader</font> may also be a list, in which case the length of
the leader is equal to that of the list, and the elements are
initialized to the elements of the list, in reverse order (i.e., the
car of the list is stored in the highest-subscripted location in the
leader).

	If <font class="italic">index-offset</font> is present, <font class="italic">displaced-p</font> should be an
array, and <font class="italic">index-offset</font> should be a fixnum; it is made to be the
index-offset of the created indirect array. (See <a href='fd_arr.html#index-offset'>this link</a>.)
<p class='cindent'><!-- "index offset" -->

	If <font class="italic">named-structure</font> is not <font class="lisp">nil</font>, it is a symbol to
be stored in the named-structure cell element of the array.  The array
created will be a named structure (see <a href='dfstr.html#named-structure'>this link</a>.)
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(make-array nil 'art-q 5 nil 3)   <font class="main">;;leader 3 elements long.</font>
(setq a (make-array nil 'art-1b 100 nil '(t nil)))
(array-leader a 0) =&gt; nil
(array-leader a 1) =&gt; t
</pre>
<p class='cindent'><!-- "array leader" -->

	<font class="lisp">make-array</font> returns the newly-created array, and also returns, as
a second value, the number of words allocated from <font class="italic">area</font> in the process
of creating the array.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-displaced-p <font class='italic' color='purple'>array</font></font></font><br>
<font class="italic">array</font> may be any kind of array.
This predicate returns <font class="lisp">t</font> if <font class="italic">array</font> is any kind of displaced array
(including indirect arrays).  Otherwise it returns <font class="lisp">nil</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-indirect-p <font class='italic' color='purple'>array</font></font></font><br>
<font class="italic">array</font> may be any kind of array.
This predicate returns <font class="lisp">t</font> if <font class="italic">array</font> is an indirect array.
Otherwise it returns <font class="lisp">nil</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-indexed-p <font class='italic' color='purple'>array</font></font></font><br>
<font class="italic">array</font> may be any kind of array.
This predicate returns <font class="lisp">t</font> if <font class="italic">array</font> is an indirect array with an index-offset.
Otherwise it returns <font class="lisp">nil</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>adjust-array-size <font class='italic' color='purple'>array new-size</font></font></font><br>
	<font class="italic">array</font> should be a one-dimensional array.  Its size is
changed to be <font class="italic">new-size</font>.  If this results in making <font class="italic">array</font>
smaller, then the extra elements are lost; if <font class="italic">array</font> is made
bigger, the new elements are initialized in the same fashion as
<font class="lisp">make-array</font> (see (make-array-fun)): either to <font class="lisp">nil</font> or <font class="lisp">0</font>. 
[Currently there is a bug which causes initialization to zero not to work.]
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(setq a (make-array nil 'art-q 5))
(aset 'foo a 4)
(aref a 4) =&gt; foo
(adjust-array-size a 2)
(aref a 4) =&gt; ERROR
</pre>
	If the size of the array is being increased, <font class="lisp">adjust-array-size</font>
must allocate a new array somewhere; it then alters <font class="italic">array</font> so that
references to it will be made to the new array instead, by means of
an "invisible pointer".  <font class="lisp">adjust-array-size</font> will return this
new array if it creates one, and otherwise it will return <font class="italic">array</font>.
Be careful about using the returned result of <font class="lisp">adjust-array-size</font>,
because you may end up holding two arrays which are not the same
(i.e., not <font class="lisp">eq</font>) which share the same contents.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>return-array <font class='italic' color='purple'>array</font></font></font><br>
Return <font class="italic">array</font> to free storage.  If it is displaced,
this returns the pointer, not the data pointed to.  Currently
does nothing if the array is not at the end of its area.
This will eventually be renamed to <font class="lisp">reclaim</font>, when
it works for other objects than arrays.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>aref <font class='italic' color='purple'>array &rest subscripts</font></font></font><br>
Returns the element of <font class="italic">array</font> selected by the <font class="italic">subscripts</font>.
The <font class="italic">subscripts</font> must be fixnums and their number must match the
dimensionality of <font class="italic">array</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>ar-1 <font class='italic' color='purple'>array i</font></font></font><br>
<font class="italic">array</font> should be a one-dimensional array, and <font class="italic">i</font> should be a
fixnum.  This returns the <font class="italic">i</font>'th element of <font class="italic">array</font>. 
</div>

<div class='defun'><font class='exdent'><font class='funcname'>ar-2 <font class='italic' color='purple'>array i j</font></font></font><br>
<font class="italic">array</font> should be a two-dimensional array, and <font class="italic">i</font> and <font class="italic">j</font> should be 
fixnums.  This returns the <font class="italic">i</font> by <font class="italic">j</font>'th element of <font class="italic">array</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>ar-3 <font class='italic' color='purple'>array i j k</font></font></font><br>
<font class="italic">array</font> should be a three-dimensional array, and <font class="italic">i</font>, <font class="italic">j</font>, and
<font class="italic">k</font> should be  fixnums.  This returns the <font class="italic">i</font> by <font class="italic">j</font> by <font class="italic">k</font>'th
element of <font class="italic">array</font>. 
</div>

<div class='defun'><font class='exdent'><font class='funcname'>aset <font class='italic' color='purple'>x array &rest subscripts</font></font></font><br>
Stores <font class="italic">x</font> into the element of <font class="italic">array</font> selected by the <font class="italic">subscripts</font>.
The <font class="italic">subscripts</font> must be fixnums and their number must match the
dimensionality of <font class="italic">array</font>.  The returned value is <font class="italic">x</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>as-1 <font class='italic' color='purple'>x array i</font></font></font><br>
<font class="italic">array</font> should be a one-dimensional array, and <font class="italic">i</font> should be a
fixnum.  <font class="italic">x</font> may be any object.  <font class="italic">x</font> is stored in the <font class="italic">i</font>'th element
of <font class="italic">array</font>.  <font class="lisp">as-1</font> returns <font class="italic">x</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>as-2 <font class='italic' color='purple'>x array i j</font></font></font><br>
<font class="italic">array</font> should be a two-dimensional array, and <font class="italic">i</font> and <font class="italic">j</font> should be 
fixnums.  <font class="italic">x</font> may be any object.  <font class="italic">x</font> is stored in the <font class="italic">i</font> by <font class="italic">j</font>'th
element of <font class="italic">array</font>.  <font class="lisp">as-2</font> returns <font class="italic">x</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>as-3 <font class='italic' color='purple'>x array i j k</font></font></font><br>
<font class="italic">array</font> should be a three-dimensional array, and <font class="italic">i</font>, <font class="italic">j</font>, and
<font class="italic">k</font> should be fixnums.  <font class="italic">x</font> may be any object.  <font class="italic">x</font> is stored in
the <font class="italic">i</font> by <font class="italic">j</font> by <font class="italic">k</font>'th element of <font class="italic">array</font>.  <font class="lisp">as-3</font> returns
<font class="italic">x</font>. 
</div>

<div class='defun'><font class='exdent'><font class='funcname'>aloc <font class='italic' color='purple'>array &rest subscripts</font></font></font><br>
Returns a locative pointer to the element-cell of <font class="italic">array</font> selected by
the <font class="italic">subscripts</font>.  The <font class="italic">subscripts</font> must be fixnums and their
number must match the dimensionality of <font class="italic">array</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>ap-1 <font class='italic' color='purple'>array i</font></font></font><br>
<font class="italic">array</font> should be a one-dimensional array whose elements contain Lisp
objects, and <font class="italic">i</font> should be a
fixnum.  This returns a locative pointer to the <font class="italic">i</font>'th element of
<font class="italic">array</font>.  See the explanation of locatives, <a href='fd_loc.html#locative'>this link</a>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>ap-2 <font class='italic' color='purple'>array i j</font></font></font><br>
<font class="italic">array</font> should be a two-dimensional array whose elements contain Lisp
objects, and <font class="italic">i</font> and <font class="italic">j</font>
should be  fixnums.  This returns a locative pointer to the <font class="italic">i</font> by
<font class="italic">j</font>'th element of <font class="italic">array</font>.  See the explanation of locatives, <a href='fd_loc.html#locative'>this link</a>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>ap-3 <font class='italic' color='purple'>array i j k</font></font></font><br>
<font class="italic">array</font> should be a three-dimensional array whose elements contain Lisp
objects, and <font class="italic">i</font>, <font class="italic">j</font>, and
<font class="italic">k</font> should be  fixnums.  This returns a locative pointer to the
<font class="italic">i</font> by <font class="italic">j</font> by <font class="italic">k</font>'th element of <font class="italic">array</font>.
See the explanation of locatives, <a href='fd_loc.html#locative'>this link</a>.
</div>

The compiler turns <font class="lisp">aref</font> into <font class="lisp">ar-1</font>, <font class="lisp">ar-2</font>, etc. according
to the number of subscripts specified, turns <font class="lisp">aset</font> into <font class="lisp">as-1</font>,
<font class="lisp">as-2</font>, etc., and turns <font class="lisp">aloc</font> into <font class="lisp">ap-1</font>, <font class="lisp">ap-2</font>, etc.
For arrays with more than 3 dimensions the compiler uses the slightly less
efficient form since the special routines only exist for 1, 2, and 3 dimensions.
There is no reason for any program to call <font class="lisp">ar-1</font>, <font class="lisp">as-1</font>, <font class="lisp">ar-2</font>, etc.
explicitly; they are documented because there used to be such a reason, and
many existing programs use these functions.  New programs should use <font class="lisp">aref</font>,
<font class="lisp">aset</font>, and <font class="lisp">aloc</font>.

<div class='defun'><font class='exdent'><font class='funcname'>arraycall <font class='italic' color='purple'>ignored array &rest subscripts</font></font></font><br>
<font class="lisp">(arraycall nil <font class="italic">array</font> <font class="italic">sub1</font> <font class="italic">sub2</font>...)</font> is the same
as <font class="lisp">(aref <font class="italic">array</font> <font class="italic">sub1</font> <font class="italic">sub2</font>...)</font>.  It exists for
Maclisp compatibility.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>get-list-pointer-into-array <font class='italic' color='purple'>array-ref</font></font></font><br>
<!-- This will probably be renamed, if anyone can think of a better name -->
The argument <font class="italic">array-ref</font> is ignored, but should be a reference
to an <font class="lisp">art-q-list</font> array by applying the array to subscripts (rather
than by <font class="lisp">aref</font>).  This returns a list object which
is a portion of the "list" of the array, beginning with the last
element of the array which has been referenced.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>g-l-p <font class='italic' color='purple'>array</font></font></font><br>
<!-- This will probably be renamed, if anyone can think of a better name -->
<font class="italic">array</font> should be an <font class="lisp">art-q-list</font> array.  This returns
a list which shares the storage of <font class="italic">array</font>.  The <font class="lisp">art-q-list</font>
type exists so that <font class="lisp">g-l-p</font> can be used.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(setq a (make-array nil 'art-q-list 4))
(aref a 0) =&gt; nil
(setq b (g-l-p a)) =&gt; (nil nil nil nil)
(rplaca b t)
b =&gt; (t nil nil nil)
(aref a 0) =&gt; t
(aset 30 a 2)
b =&gt; (t nil 30 nil)
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>get-locative-pointer-into-array <font class='italic' color='purple'>array-ref</font></font></font><br>
<!-- This will probably be flushed? -->
<font class="lisp">get-locative-pointer-into-array</font> is
similar to <font class="lisp">get-list-pointer-into-array</font>, except that it returns a
locative, and doesn't require the array to be <font class="lisp">art-q-list</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>arraydims <font class='italic' color='purple'>array</font></font></font><br>
<font class="italic">array</font> may be any array; it also may be a symbol whose
function cell contains an array, for Maclisp compatibility
(see (maclisp-array)).
It returns a list whose first element is the symbolic name of
the type of <font class="italic">array</font>, and whose remaining elements are its dimensions.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(setq a (make-array nil 'art-q '(3 5)))
(arraydims a) =&gt; (art-q 3 5)
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-dimensions <font class='italic' color='purple'>array</font></font></font><br>
<font class="lisp">array-dimensions</font> returns a list whose elements are the dimensions
of <font class="italic">array</font>.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(setq a (make-array nil 'art-q '(3 5)))
(array-dimensions a) =&gt; (3 5)
</pre>
Note: the list returned by <font class="lisp">(array-dimensions <font class="italic">x</font>)</font> is
equal to the cdr of the list returned by <font class="lisp">(arraydims <font class="italic">x</font>)</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-in-bounds-p <font class='italic' color='purple'>array &rest subscripts</font></font></font><br>
This function checks whether the <font class="italic">subscripts</font> are all
legal subscripts for <font class="italic">array</font>, and returns <font class="lisp">t</font> if they
are; otherwise it returns <font class="lisp">nil</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-length <font class='italic' color='purple'>array</font></font></font><br>
<font class="italic">array</font> may be any array.  This returns the total number
of elements in <font class="italic">array</font>.  For a one-dimensional array,
this is one greater than the maximum allowable subscript.
(But if fill pointers are being used, you may want to use
<font class="lisp">array-active-length</font> (see (array-active-length-fun))).
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(array-length (make-array nil 'art-q 3)) =&gt; 3
(array-length (make-array nil 'art-q '(3 5)))
		=&gt; 17  <font class="main">;octal, which is 15. decimal</font>
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-/#-dims <font class='italic' color='purple'>array</font></font></font><br>
Returns the dimensionality of <font class="italic">array</font>.  Note that the name of the
function includes a "#", which must be slashified if you want to be
able to compile your program with the compiler running in Maclisp.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(array-/#-dims (make-array nil 'art-q '(3 5))) =&gt; 2
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-dimension-n <font class='italic' color='purple'>n array</font></font></font><br>
<font class="italic">array</font> may be any kind of array, and <font class="italic">n</font> should be a fixnum.
If <font class="italic">n</font> is between 1 and the dimensionality of <font class="italic">array</font>,
this returns the <font class="italic">n</font>'th dimension of <font class="italic">array</font>.  If <font class="italic">n</font> is <font class="lisp">0</font>,
it returns the length of the leader of <font class="italic">array</font>; if <font class="italic">array</font> has no
leader it returns <font class="lisp">nil</font>.  If <font class="italic">n</font> is any other value, it
returns <font class="lisp">nil</font>.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(setq a (make-array nil 'art-q '(3 5) nil 7))
(array-dimension-n 1 a) =&gt; 3
(array-dimension-n 2 a) =&gt; 5
(array-dimension-n 3 a) =&gt; nil
(array-dimension-n 0 a) =&gt; 7
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-type <font class='italic' color='purple'>array</font></font></font><br>
Returns the symbolic type of <font class="italic">array</font>.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(setq a (make-array nil 'art-q '(3 5)))
(array-type a) =&gt; art-q
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>fillarray <font class='italic' color='purple'>array x</font></font></font><br>
Note: for the present, all arrays concerned must be one-dimensional.
	<font class="italic">array</font> may be any type of array, or, for Maclisp
compatibility, a symbol whose function cell contains an array.  There
are two forms of this function, depending on the type of <font class="italic">x</font>. 
	If <font class="italic">x</font> is a list, then <font class="lisp">fillarray</font> fills up <font class="italic">array</font> with
the elements of <font class="italic">list</font>.  If <font class="italic">x</font> is too short to fill up all of
<font class="italic">array</font>, then the last element of <font class="italic">x</font> is used to fill the
remaining elements of <font class="italic">array</font>.  If <font class="italic">x</font> is too long, the extra
elements are ignored. 
	If <font class="italic">x</font> is an array (or, for Maclisp compatibility, a symbol
whose function cell contains an array), then the elements of <font class="italic">array</font> are
filled up from the elements of <font class="italic">x</font>.  If <font class="italic">x</font> is too small, then
the extra elements of <font class="italic">array</font> are not affected.
	<font class="lisp">fillarray</font> returns <font class="italic">array</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>listarray <font class='italic' color='purple'>array &optional limit</font></font></font><br>
Note: for the present, all arrays concerned must be one-dimensional.
	<font class="italic">array</font> may be any type of array, or, for Maclisp
compatibility, a symbol whose function cell contains an array.  
<font class="lisp">listarray</font> creates and returns a list whose elements are those of
<font class="italic">array</font>.  If <font class="italic">limit</font> is present, it should be a fixnum, and only
the first <font class="italic">limit</font> (if there are more than that many) elements of
<font class="italic">array</font> are used, and so the maximum length of the returned list is
<font class="italic">limit</font>. 
</div>

<div class='defun'><font class='exdent'><font class='funcname'>copy-array-contents <font class='italic' color='purple'>from to</font></font></font><br>
<font class="italic">from</font> and <font class="italic">to</font> must be arrays.  The contents of <font class="italic">from</font>
is copied into the contents of <font class="italic">to</font>, element by element.
<font class="italic">Presently the first subscript varies fastest
in multi-dimensional arrays (opposite from Maclisp).</font>
If <font class="italic">to</font> is shorter than <font class="italic">from</font>,
the excess is ignored.  If <font class="italic">from</font> is shorter than
<font class="italic">to</font>, the rest of <font class="italic">to</font> is filled with <font class="lisp">nil</font> if it
is a q-type array or 0 if it is a numeric array or 200 if it is a string.
<font class="lisp">t</font> is always returned.

Note that even if <font class="italic">from</font> or <font class="italic">to</font> has a leader, the whole array
is used; the convention with leader element 0 being the "active" length
of the array is not used by this function.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>copy-array-portion <font class='italic' color='purple'>from-array from-start from-end to-array to-start to-end</font></font></font><br>
The portion of the array <font class="italic">from-array</font> with indices greater than or
equal to <font class="italic">from-start</font> and less than <font class="italic">from-end</font> is copied into
the portion of the array <font class="italic">to-array</font> with indices greater than or
equal to <font class="italic">to-start</font> and less than <font class="italic">to-end</font>, element by element.
If there are more elements in <font class="italic">to-array</font>, the extra elements are filled as
in <font class="lisp">copy-array-contents</font>.
<font class="lisp">t</font> is always returned.
</div>

<div class='section'>4.5 Array Leaders</div><p class='cindent'><!-- "array leader" -->
	Array leaders were introduced at the beginning of the chapter.
This section presents various functions which operate on array leaders.

<div class='defun'><font class='exdent'><font class='funcname'>array-has-leader-p <font class='italic' color='purple'>array</font></font></font><br>
<font class="italic">array</font> may be any array.  This predicate returns <font class="lisp">t</font> if <font class="italic">array</font>
has a leader; otherwise it returns <font class="lisp">nil</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-leader-length <font class='italic' color='purple'>array</font></font></font><br>
<font class="italic">array</font> may be any array.  This returns the length of <font class="italic">array</font>'s leader
if it has one, or <font class="lisp">nil</font> if it does not.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-leader <font class='italic' color='purple'>array i</font></font></font><br>
<font class="italic">array</font> should be an array with a leader, and <font class="italic">i</font> should be a
fixnum.  This returns the <font class="italic">i</font>'th element of <font class="italic">array</font>'s leader.
This is analogous to <font class="lisp">aref</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>store-array-leader <font class='italic' color='purple'>x array i</font></font></font><br>
<font class="italic">array</font> should be an array with a leader, and <font class="italic">i</font> should be a
fixnum.  <font class="italic">x</font> may be any object.  <font class="italic">x</font> is stored in the <font class="italic">i</font>'th element
of <font class="italic">array</font>'s leader.  <font class="lisp">store-array-leader</font> returns <font class="italic">x</font>.
This is analogous to <font class="lisp">aset</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>ap-leader <font class='italic' color='purple'>array i</font></font></font><br>
<font class="italic">array</font> should be an array with a leader, and <font class="italic">i</font> should be a
fixnum.  This returns a locative pointer to the <font class="italic">i</font>'th element of
<font class="italic">array</font>'s leader.  See the explanation of locatives, <a href='fd_loc.html#locative'>this link</a>.
This is analogous to <font class="lisp">aloc</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-active-length <font class='italic' color='purple'>array</font></font></font><br>
If <font class="italic">array</font> does not have a fill pointer, then this returns whatever
<font class="lisp">(array-length <font class="italic">array</font>)</font> would have.  If <font class="italic">array</font> does have a
fill pointer, <font class="lisp">array-active-length</font> returns it.  See the general
explanation of the use of fill pointers, which is at the beginning of
this section.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-push <font class='italic' color='purple'>array x</font></font></font><br>
<font class="italic">array</font> must be a one-dimensional array which has a fill pointer, and <font class="italic">x</font> may
be any object.  <font class="lisp">array-push</font> attempts to store <font class="italic">x</font> in the element
of the array designated by the fill pointer, and increase the fill pointer
by one.  If the fill pointer does not designate an element of the array (specifically,
when it gets too big), it is unaffected and <font class="lisp">array-push</font> returns <font class="lisp">nil</font>;
otherwise, the two actions (storing and incrementing) happen uninterruptibly,
and <font class="lisp">array-push</font> returns the <font class="italic">former</font> value of the fill pointer
(one less than the one it leaves in the array).  If the array is of type
<font class="lisp">art-q-list</font>, an operation similar to <font class="lisp">nconc</font> has taken place,
in that the element has been added to the list by changing the cdr of
the formerly last element.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-push-extend <font class='italic' color='purple'>array x</font></font></font><br>
<font class="lisp">array-push-extend</font> is just like <font class="lisp">array-push</font> except
that if the fill pointer gets too large, the array is grown
to fit the new element; i.e. it never "fails" the way <font class="lisp">array-push</font> does,
and so never returns <font class="lisp">nil</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>array-pop <font class='italic' color='purple'>array</font></font></font><br>
<font class="italic">array</font> must be a one-dimensional array which has a fill pointer.
The fill pointer is decreased by one, and the array element
designated by the new value of the fill pointer is returned.
If the new value does not designate any element of the array
(specifically, if it has reached zero), an error is caused.
The two operations (decrementing and array referencing) happen
uninterruptibly.  If the array is of type <font class="lisp">art-q-list</font>, an operation
similar to <font class="lisp">nbutlast</font> has taken place.
<!-- ??? or will, anyway. -->
</div>

<div class='defun'><font class='exdent'><font class='funcname'>list-array-leader <font class='italic' color='purple'>array &optional limit</font></font></font><br>
<font class="italic">array</font> may be any type of array, or, for Maclisp
compatibility, a symbol whose function cell contains an array.  
<font class="lisp">list-array-leader</font> creates and returns a list whose elements are those of
<font class="italic">array</font>'s leader.  If <font class="italic">limit</font> is present, it should be a fixnum, and only
the first <font class="italic">limit</font> (if there are more than that many) elements of
<font class="italic">array</font>'s leader are used, and so the maximum length of the returned list is
<font class="italic">limit</font>. If <font class="italic">array</font> has no leader, <font class="lisp">nil</font> is returned.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>copy-array-contents-and-leader <font class='italic' color='purple'>from to</font></font></font><br>
This is just like <font class="lisp">copy-array-contents</font> (see (copy-array-contents-fun)), but the leaders
of <font class="italic">from</font> and <font class="italic">to</font> are also copied.
</div>

<div class='section'>4.6 Maclisp Array Compatibility</div>	Note: the functions in this section should not be used in new
programs.
	In Maclisp, arrays are usually kept on the <font class="lisp">array</font> property
of symbols, and the symbols are used instead of the arrays.  In order
to provide some degree of compatibility for this manner of using
arrays, the <font class="lisp">array</font>, <font class="lisp">*array</font>, and <font class="lisp">store</font> functions are
provided, and when arrays are applied to arguments, the arguments are
treated as subscripts and <font class="lisp">apply</font> returns the corresponding element
of the array.  However, the <font class="lisp">*rearray</font>, <font class="lisp">loadarrays</font>, and
<font class="lisp">dumparrays</font> functions are not provided.  Also, <font class="lisp">flonum</font>,
<font class="lisp">readtable</font>, and <font class="lisp">obarray</font> type arrays are not supported.  

<div class='defun'><font class='exdent'><font class='funcname'>array <font class='italic' color='purple'>&quote symbol type &eval &rest dims</font></font></font><br>
	This creates an <font class="lisp">art-q</font> type array in <font class="lisp">default-array-area</font>
with the given dimensions.  (That is, <font class="italic">dims</font> is given
to <font class="lisp">make-array</font> as its third argument.)  <font class="italic">type</font> is ignored.
If <font class="italic">symbol</font> is <font class="lisp">nil</font>, the array is returned; otherwise,
the array is put in the function cell of <font class="italic">symbol</font>, and <font class="italic">symbol</font>
is returned.
</div>


<div class='defun'><font class='exdent'><font class='funcname'>*array <font class='italic' color='purple'>symbol type &rest dims</font></font></font><br>
	This is just like <font class="lisp">array</font>, except that all of the arguments
are evaluated.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>store <font class='italic' color='purple'>&quote array-ref x</font></font></font><br>
<font class="italic">x</font> may be any object; <font class="italic">array-ref</font> should be a form which
references an array by calling it as a function (<font class="lisp">aref</font> forms are not
acceptable).  First <font class="italic">x</font> is evaluated, then <font class="italic">array-ref</font> is
evaluated, and then the value of <font class="italic">x</font> is stored into the array cell
which was referenced by the evaluation of <font class="italic">array-ref</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>xstore <font class='italic' color='purple'>x array-ref</font></font></font><br>
	This is just like <font class="lisp">store</font>, but it is not
a special form; this is because the arguments are in the other
order.  This function only exists for the compiler to compile the
<font class="lisp">store</font> special form, and should never be used by programs.
</div>
.eof
</body>
</html>

